EnigmA Amiga Run 1997 April

home *** CD-ROM | disk | FTP | other *** search

/ EnigmA Amiga Run 1997 April / EnigmA AMIGA RUN 17 (1997)(G.R. Edizioni)(IT)[!][issue 1997-04][EAR-CD].iso / EARCD / comm / misc / amigancp19.lha / AmigaNCP19 / Developer / Autodocs / AmigaNCP.doc

Wrap

Text File | 1996-10-27 | 22KB | 963 lines

TABLE OF CONTENTS amigancp.library/--pools-- amigancp.library/NCP_AbortRead amigancp.library/NCP_AbortWrite amigancp.library/NCP_BeginRead amigancp.library/NCP_BeginWrite amigancp.library/NCP_CheckRead amigancp.library/NCP_CheckWrite amigancp.library/NCP_clnl amigancp.library/NCP_CloseChannel amigancp.library/NCP_Fault amigancp.library/NCP_ibm2iso amigancp.library/NCP_ILONG amigancp.library/NCP_ILONGP amigancp.library/NCP_ILONGPI amigancp.library/NCP_iso2ibm amigancp.library/NCP_IWORD amigancp.library/NCP_IWORDP amigancp.library/NCP_IWORDPI amigancp.library/NCP_LinkRemoteRun amigancp.library/NCP_OpenChannel amigancp.library/NCP_Read amigancp.library/NCP_ReadSig amigancp.library/NCP_tab_ibm2iso amigancp.library/NCP_tab_iso2ibm amigancp.library/NCP_WaitRead amigancp.library/NCP_WaitWrite amigancp.library/NCP_Write amigancp.library/NCP_WriteSig amigancp.library/--pools-- amigancp.library/--pools-- The amigancp.library contains a clone set of the standard AmigaOS memory pool functions to ensure compatibility with OS 2.x systems. The exec pool functions were seriously broken in the 2.x releases of AmigaOS. NCP_CreatePool() NCP_DeletePool() NCP_AllocPooled() NCP_FreePooled() See the exec.library documentation for more information about these functions. amigancp.library/NCP_AbortRead amigancp.library/NCP_AbortRead NAME NCP_AbortRead -- abort read currently in progress SYNOPSIS NCP_AbortRead( channel ) A0 void NCP_AbortRead( APTR ) FUNCTION Aborts the current read request on the given NCP channel. Does nothing if no read is pending. INPUTS channel -- a NCP channel created by NCP_OpenChannel() RESULT None. EXAMPLE NOTES Never forget to finish a read request using NCP_WaitRead(), or you'll end up in OS hell. BUGS None known. SEE ALSO NCP_Read(), NCP_WaitRead(), NCP_CheckRead(), NCP_BeginRead() amigancp.library/NCP_AbortWrite amigancp.library/NCP_AbortWrite NAME NCP_AbortWrite -- abort write currently in progress SYNOPSIS NCP_AbortWrite( channel ) A0 void NCP_AbortWrite( APTR ) FUNCTION Aborts the current write request on the given NCP channel. Does nothing if no write is pending. INPUTS channel -- a NCP channel created by NCP_OpenChannel() RESULT None. EXAMPLE NOTES Never forget to finish a write request using NCP_WaitWrite(), or you'll end up in OS hell. BUGS None known. SEE ALSO NCP_Write(), NCP_WaitWrite(), NCP_CheckWrite(), NCP_BeginWrite() amigancp.library/NCP_BeginRead amigancp.library/NCP_BeginRead NAME NCP_BeginRead -- start a read request on the NCP channel. SYNOPSIS error = NCP_BeginRead( channel, data, datasize ) D0 A0 A1 D0 LONG NCP_BeginRead( APTR, APTR, ULON G); FUNCTION Queues a read operation on the current NCP channel. INPUTS channel -- a NCP channel created by NCP_OpenChannel() data -- receive buffer datasize -- receive buffer size RESULT error -- either 0 if the read was queued successfully or a negative error number EXAMPLE NOTES Only one read request may be queued at a time on a single channel. This function fails with NCPE_INUSE if there is already a read request outstanding. BUGS None known. SEE ALSO NCP_Read(), NCP_WaitRead(), NCP_AbortRead(), NCP_CheckRead() amigancp.library/NCP_BeginWrite amigancp.library/NCP_BeginWrite NAME NCP_BeginWrite -- start a write request on the NCP channel. SYNOPSIS error = NCP_BeginWrite( channel, data, datasize ) D0 A0 A1 D0 LONG NCP_BeginWrite( APTR, APTR, ULON G); FUNCTION Queues a write operation on the current NCP channel. INPUTS channel -- a NCP channel created by NCP_OpenChannel() data -- data buffer datasize -- data buffer size RESULT error -- either 0 if the write was queued successfully or a negative error number EXAMPLE NOTES Only one write request may be queued at a time on a single channel. This function fails with NCPE_INUSE if there is already a write request outstanding. BUGS None known. SEE ALSO NCP_Write(), NCP_WaitWrite(), NCP_AbortWrite(), NCP_CheckWrite() amigancp.library/NCP_CheckRead amigancp.library/NCP_CheckRead NAME NCP_CheckRead -- check if a read request is still pending SYNOPSIS status = NCP_CheckRead( channel ) D0 A0 LONG NCP_CheckRead( APTR ) FUNCTION Check if a read request is still pending on the given NCP channel. INPUTS channel -- a NCP channel created by NCP_OpenChannel() RESULT status -- FALSE if a read is currently pending, TRUE if no request is pending or the current request has completed. EXAMPLE NOTES Never forget to finish a read request using NCP_WaitRead(), or you'll end up in OS hell. BUGS None known. SEE ALSO NCP_Read(), NCP_WaitRead(), NCP_AbortRead(), NCP_BeginRead() amigancp.library/NCP_CheckWrite amigancp.library/NCP_CheckWrite NAME NCP_CheckWrite -- check if a write request is still pending SYNOPSIS status = NCP_CheckWrite( channel ) D0 A0 LONG NCP_CheckWrite( APTR ) FUNCTION Check if a write request is still pending on the given NCP channel. INPUTS channel -- a NCP channel created by NCP_OpenChannel() RESULT status -- FALSE if a write is currently pending, TRUE if no request is pending or the current request has completed. EXAMPLE NOTES Never forget to finish a write request using NCP_WaitWrite(), or you'll end up in OS hell. BUGS None known. SEE ALSO NCP_Write(), NCP_WaitWrite(), NCP_AbortWrite(), NCP_BeginWrite() amigancp.library/NCP_clnl amigancp.library/NCP_clnl NAME NCP_clnl -- clear CR/LF at end of line. SYNOPSIS NCP_clnl( string ) A0 void NCP_clnl( STRPTR ); FUNCTION Clears any CR or LF characters at the end of the string. INPUTS string -- pointer to string (contents will be modified) RESULT None. EXAMPLE NOTES BUGS None known. SEE ALSO amigancp.library/NCP_CloseChannel amigancp.library/NCP_CloseChannel NAME NCP_CloseChannel -- close a NCP channel SYNOPSIS NCP_CloseChannel( channel ) A0 void NCP_CloseChannel( APTR ); FUNCTION Close a NCP channel previously opened by NCP_OpenChannel(). If this is an active link to the remote machine, it will be closed. INPUTS channel -- channel to close. May be NULL, in which case this functions does nothing. RESULT None. EXAMPLE NOTES An active NCP connection will be dropped about 10s after the last channel has been closed. BUGS None known. SEE ALSO NCP_OpenChannel() amigancp.library/NCP_Fault amigancp.library/NCP_Fault NAME NCP_Fault -- return localized NCP error string SYNOPSIS NCP_Fault( code, header, buffer, buffersize ); D0 A0 A1 D1 void NCP_Fault( LONG, STRPTR, STRPTR, ULONG ); FUNCTION Returns a localized text string associated with the error code. INPUTS code -- NCP error code header -- header to insert before string. May be NULL buffer -- buffer to write the error text to buffersize -- size of buffer RESULT None. EXAMPLE NOTES BUGS None known. SEE ALSO dos.library/Fault() amigancp.library/NCP_ibm2iso amigancp.library/NCP_ibm2iso NAME NCP_ibm2iso -- convert IBM to ISO charachter SYNOPSIS isochar = NCP_ibm2iso( ibmchar ) D0 D0 0:7 UBYTE NCP_ibm2iso( UBYTE ); FUNCTION Converts a character from the IBM to the ISO charset. INPUTS ibmchar -- character of the IBM codeset RESULT isochar -- equivalent character in the ISO codeset EXAMPLE NOTES BUGS None known. SEE ALSO amigancp.library/NCP_ILONG amigancp.library/NCP_ILONG NAME NCP_ILONG -- swap bytes in longword SYNOPSIS slongword = NCP_ILONG( longword ) D0 D0 ULONG NCP_ILONG( ULONG ); FUNCTION Swaps the byte order within the longword. INPUTS longword -- a 32 bit data word. RESULT slongword -- the same word with the byte order swapped. EXAMPLE NOTES BUGS None known. SEE ALSO amigancp.library/NCP_ILONGP amigancp.library/NCP_ILONGP NAME NCP_ILONGP -- swap bytes in longword (pointer version) SYNOPSIS sword = NCP_ILONGP( longwordp1, longwordp2 ) D0 A0 A1 ULONG NCP_ILONGP( ULONG *, ULONG * ); FUNCTION Swaps the byte order from the longword pointed to by longwordp1 and places the result in the longword pointed to by longwordp2. INPUTS longwordp1 -- pointer to source longword longwordp2 -- pointer to destination longword RESULT sword -- the same word with the byte order swapped. EXAMPLE NOTES The longwords don't need to be word aligned. BUGS The 68020++ version of amigancp.library requires the hardware to be able to do misaligned word accesses. Some early accelerator boards may have problems doing this. SEE ALSO amigancp.library/NCP_ILONGPI amigancp.library/NCP_ILONGPI NAME NCP_ILONGPI -- swap bytes in longword (in-place pointer version) SYNOPSIS sword = NCP_ILONGPI( longwordp ) D0 A0 ULONG NCP_ILONGP( ULONG * ) FUNCTION Swaps the byte order within the longword pointed to by longwordp. INPUTS longwordp -- pointer to longword to swap RESULT sword -- the same word with the byte order swapped. EXAMPLE NOTES The longword doesn't need to be word aligned. BUGS The 68020++ version of amigancp.library requires the hardware to be able to do misaligned word accesses. Some early accelerator boards may have problems doing this. SEE ALSO amigancp.library/NCP_iso2ibm amigancp.library/NCP_iso2ibm NAME NCP_iso2ibm -- convert IBM to ISO charachter SYNOPSIS ibmchar = NCP_iso2ibm( isochar ) D0 D0 0:7 UBYTE NCP_iso2ibm( UBYTE ); FUNCTION Converts a character from the ISO to the IBM charset. INPUTS isochar -- character of the ISO codeset RESULT ibmchar -- equivalent character in the IBM codeset EXAMPLE NOTES BUGS None known. SEE ALSO amigancp.library/NCP_IWORD amigancp.library/NCP_IWORD NAME NCP_IWORD -- swap bytes in word SYNOPSIS sword = NCP_IWORD( word ) D0 D0 UWORD NCP_IWORD( UWORD ); FUNCTION Swaps the byte order within the word. INPUTS word -- a 16 bit data word. RESULT sword -- the same word with the byte order swapped. EXAMPLE NOTES BUGS None known. SEE ALSO amigancp.library/NCP_IWORDP amigancp.library/NCP_IWORDP NAME NCP_IWORDP -- swap bytes in word (pointer version) SYNOPSIS sword = NCP_IWORDP( wordp1, wordp2 ) D0 A0 A1 UWORD NCP_IWORDP( UWORD *, UWORD * ); FUNCTION Swaps the byte order from the word pointed to by wordp1 and places the result in the word pointed to by wordp2. INPUTS wordp1 -- pointer to source word wordp2 -- pointer to destination word RESULT sword -- the same word with the byte order swapped. EXAMPLE NOTES The words don't need to be word aligned. BUGS The 68020++ version of amigancp.library requires the hardware to be able to do misaligned word accesses. Some early accelerator boards may have problems doing this. SEE ALSO amigancp.library/NCP_IWORDPI amigancp.library/NCP_IWORDPI NAME NCP_IWORDPI -- swap bytes in word (in-place pointer version) SYNOPSIS sword = NCP_IWORDPI( wordp1 ) D0 A0 UWORD NCP_IWORDP( UWORD * ) FUNCTION Swaps the byte order within the word pointed to by wordp. INPUTS wordp -- pointer to word to swap RESULT sword -- the same word with the byte order swapped. EXAMPLE NOTES The word doesn't need to be word aligned. BUGS The 68020++ version of amigancp.library requires the hardware to be able to do misaligned word accesses. Some early accelerator boards may have problems doing this. SEE ALSO amigancp.library/NCP_LinkRemoteRun amigancp.library/NCP_LinkRemoteRun NAME NCP_LinkRemoteRun -- use the NCP link channel to run a program on the remote machine. SYNOPSIS error = NCP_LinkRemoteRun( filename, cmdline, cmdlinelen ) D0 A0 A1 D0 LONG NCP_LinkRemoteRun( STRPTR, APTR, ULONG ); FUNCTION Use the LINK supervisor channel to have the remote link run a program. No NCP channel needs to be opened in order to perform this operation. INPUTS filename -- file name of the remote program to start cmdline -- pointer to command line array. Note that EPOC command lines are *NOT* zero terminated. cmdlinelen -- length of command line in bytes. May be zero, in which case no command line is transfered. RESULT error -- either an AmigaNCP specific error code or the result code from the remote link. EXAMPLE Have WORD.APP read the Amiga startup sequence: UBYTE cmdline[] = { "OANCPTest\000 V TES\000REM::SYS:\S\STARTUP-SEQUENCE\000" }; error = NCP_LinkRemoteRun( "WORD.APP", cmdline, sizeof( cmdline ) ); NOTES See the Psion SDK for more information about using commandlines and the LINK process launch feature. BUGS None known. SEE ALSO amigancp.library/NCP_OpenChannel amigancp.library/NCP_OpenChannel NAME NCP_OpenChannel -- open a NCP channel to attempt to connect to the remote. SYNOPSIS channel = NCP_OpenChannel( localname, remotename, flags ) D0 A0 A1 D0 APTR NCP_OpenChannel( STRPTR, STRPTR, ULONG ); FUNCTION Opens an NCP channel. If remotename is not NULL, attempts to connect to the remote process and fails with a NULL return if the connection could not be made. If remotename is NULL, creates a passive channel silently awaiting remote connection. INPUTS localname -- name of local "process" remotename -- either NULL for a passive channel or the remote process name which to connect to flags -- currently unused, leave at 0 RESULT channel -- pointer to a channel object. NULL in case of an error, whereas additional error information can be found in IoErr() EXAMPLE To connect to the remote file server: APTR channel; channel = NCP_OpenChannel( "TestHost", "SYS$RFSV.*", 0 ); NOTES Opening an active channel will result in an attempt to create an NCP connection and fail upon any error (including serial failure or inexistance of the remote process). Creating an passive channel will not cause an NCP connection attempt; this is done upon the first I/O request made to channel. BUGS None known. SEE ALSO NCP_CloseChannel() amigancp.library/NCP_Read amigancp.library/NCP_Read NAME NCP_Read -- do a read request. SYNOPSIS status = NCP_Read( channel, data, datasize ) D0 A0 LONG NCP_Read( APTR, APTR, ULONG ); FUNCTION This is basically identical to calling NCP_BeginRead() followed by NCP_WaitRead(). INPUTS channel -- a NCP channel created by NCP_OpenChannel() data -- receive buffer datasize -- receive buffer size RESULT status -- number of bytes read or a negative error number. EXAMPLE NOTES BUGS SEE ALSO NCP_WaitRead(), NCP_BeginRead(), NCP_AbortRead(), NCP_CheckRead() amigancp.library/NCP_ReadSig amigancp.library/NCP_ReadSig NAME NCP_ReadSig -- return signal mask of channel read port. SYNOPSIS sigmask = NCP_ReadSig( channel ) D0 A0 ULONG NCP_ReadSig( APTR ); FUNCTION This function returns the signal mask of the read port of the given NCP channel. This signal is set if a read request completes. INPUTS channel -- a NCP channel created by NCP_OpenChannel() RESULT sigmask -- signal mask of read port. EXAMPLE NOTES Note that this function returns a signal mask, not a signal bit number. BUGS SEE ALSO NCP_BeginRead() amigancp.library/NCP_tab_ibm2iso amigancp.library/NCP_tab_ibm2iso NAME NCP_tab_ibm2iso -- returns pointer to internal ibm2iso tab SYNOPSIS tab = NCP_tab_ibm2iso() D0/A0 UBYTE *NCP_tab_ibm2iso( void ); FUNCTION Returns a pointer to the internal ibm2iso conversion table. This allows you to do more efficient conversion. INPUTS None. RESULT tab -- pointer to 256 byte conversion table. EXAMPLE NOTES The pointer is returned both in D0 and A0. BUGS None known. SEE ALSO amigancp.library/NCP_tab_iso2ibm amigancp.library/NCP_tab_iso2ibm NAME NCP_tab_iso2ibm -- returns pointer to internal iso2ibm tab SYNOPSIS tab = NCP_tab_iso2ibm() D0/A0 UBYTE *NCP_tab_iso2ibm( void ); FUNCTION Returns a pointer to the internal ISO2IBM conversion table. This allows you to do more efficient conversion. INPUTS None. RESULT tab -- pointer to 256 byte conversion table. EXAMPLE NOTES The pointer is returned both in D0 and A0. BUGS None known. SEE ALSO amigancp.library/NCP_WaitRead amigancp.library/NCP_WaitRead NAME NCP_WaitRead -- complete a read request on the NCP channel. SYNOPSIS result = NCP_WaitRead( channel ) D0 A0 LONG NCP_WaitRead( APTR ); FUNCTION Waits for the current read request to finish and returns the result. INPUTS channel -- a NCP channel created by NCP_OpenChannel() RESULT status -- number of bytes read or a negative error number. EXAMPLE NOTES Every read request startet with NCP_BeginRead() absolutely must be followed by a NCP_WaitRead(), even if it already finished or was aborted via NCP_AbortRead(). BUGS Calling this function without an queued read request will hang up your process. SEE ALSO NCP_Read(), NCP_BeginRead(), NCP_AbortRead(), NCP_CheckRead() amigancp.library/NCP_WaitWrite amigancp.library/NCP_WaitWrite NAME NCP_WaitWrite -- complete a write request on the NCP channel. SYNOPSIS result = NCP_WaitWrite( channel ) D0 A0 LONG NCP_WaitWrite( APTR ); FUNCTION Waits for the current write request to finish and returns the result. INPUTS channel -- a NCP channel created by NCP_OpenChannel() RESULT status -- number of bytes written or a negative error number. EXAMPLE NOTES Every write request startet with NCP_BeginWrite() absolutely must be followed by a NCP_WaitWrite(), even if it already finished or was aborted via NCP_AbortWrite(). BUGS Calling this function without an queued write request will hang up your process. SEE ALSO NCP_Write(), NCP_BeginWrite(), NCP_AbortWrite(), NCP_CheckWrite() amigancp.library/NCP_Write amigancp.library/NCP_Write NAME NCP_Write -- do a write request. SYNOPSIS status = NCP_Write( channel, data, datasize ) D0 A0 A1 D0 LONG NCP_Write( APTR, APTR, ULONG ); FUNCTION This is basically identical to calling NCP_BeginWrite() followed by NCP_WaitWrite(). INPUTS channel -- a NCP channel created by NCP_OpenChannel() data -- receive buffer datasize -- receive buffer size RESULT status -- number of bytes written or a negative error number. EXAMPLE NOTES BUGS SEE ALSO NCP_WaitWrite(), NCP_BeginWrite(), NCP_AbortWrite(), NCP_CheckWrite() amigancp.library/NCP_WriteSig amigancp.library/NCP_WriteSig NAME NCP_WriteSig -- return signal mask of channel write port. SYNOPSIS sigmask = NCP_WriteSig( channel ) D0 A0 ULONG NCP_WriteSig( APTR ); FUNCTION This function returns the signal mask of the write port of the given NCP channel. This signal is set if a write request completes. INPUTS channel -- a NCP channel created by NCP_OpenChannel() RESULT sigmask -- signal mask of write port. EXAMPLE NOTES Note that this function returns a signal mask, not a signal bit number. BUGS SEE ALSO NCP_BeginWrite()